Step 1. What a Tutorial is

In an attempt to make the page easier to navigate, I posted this example page to demonstrate ways we could post tutorials. This can be taken further to other content, such as info pages, definitions and whatnot.

Tutorial Definition:
Tutorials are an essential part of the documentation, but they are a bit different than the normal docs. They are always step by step guides to doing a certain task in GeoServer, and are often cut across several areas of the documentation. They should guide a user or developer through a single set of concrete tasks, with a clear end goal. They are the first entry point for many new users, and thus should have a very high level of clarity, they must be easy to understand. The normal documentation can be viewed as more of a reference, for anyone digging into the depth of GeoServer, it should have all possible information. Tutorials should have exactly enough information to get anyone started.

A tutorial is anything with step-by-step instructions on how to do something that is suitable for any user.

Step 2. Links to Other Tutorials

Often in tutotials or other pages, you will want to link to other tutorials. To do that, and to make them stand out, have the links in bold green.

Example:
Try this tutorial on cheese that is plain and green. Once you are done that one, try this tutorial for more indepth examples.

Example Quick Tutorial Here is an example of a quick little tutorial, maybe 5 steps in length. First you get de sugar Then you get de power Then you get de women

These are good as little quickstart guides.

You can also use the excerpt-include tag that will include a section from another page:

Here is the exceprt from this page:

Here is a mini tutorial with the excerpt in it:

Example Quick Excerpt Tutorial This is the excerpt from the example tutorial page. The steps you must be aware of are: Step A Step B Step C

Step 3. Divide up the Tutorial into Steps

It is important to have your tutorial as a series of numbered steps. This will make it easy for the user to follow.
Also make sure the steps stand out from each other. You can use the header tags to do this.

Step 4. Use Pictures

Pictures are very important! They are incredibly useful for describing how to use a user interface, expecially when there are a lot of buttons and options. Your tutorial should really contain pictures. I will be dissapointed if it doesn't.

Step 5. Link to Your Tutorial

You want people to find your tutorial, so link to it form another page. Usually the parent page. Also announce on the mailing list that you wrote it.

I like the green check mark next to the green tutorial link. Posted by bowens at Sep 07, 2005 12:01